Document Copilot CLI permissions-config.json schema and persisted approvals by danmoseley · Pull Request #44916 · github/docs

danmoseley · 2026-06-25T22:43:33Z

Note

This pull request was created with the help of GitHub Copilot, and parts of the documentation were AI-generated. All schema details were verified against the Copilot CLI source.

What this changes

Expands the documentation for the Copilot CLI permissions-config.json file, which was previously documented only at a surface level.

content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md

Documents the file-resolution order (--config-dir → COPILOT_HOME → ~/.copilot/permissions-config.json) and the legacy extensionless file.
Documents the locations keying rules (Git root; linked worktrees resolve to the main repo root; submodules use their own directory; non-Git uses the cwd).
Adds a full schema table covering locations, tool_approvals, and allowed_directories, and every approval kind (commands, read, write, memory, mcp, mcp-sampling, custom-tool, extension-management, extension-permission-access) with their per-kind fields (commandIdentifiers, serverName, toolName, operation, extensionName).
Adds copy-pasteable example configurations and an explicit list of what the file does not support (deny/ask rules, default modes, URL rules, tool filtering, repository-local policy), pointing to the relevant CLI options instead.

content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md

Adds a short "persisted permissions" note explaining that answering "yes, always" to a prompt saves the decision to ~/.copilot/permissions-config.json, with a cross-link to the reference section.

Why

Users have reported that permissions-config.json is hard to configure because the schema, fields, and file location were not documented in enough detail — particularly when migrating settings from other agent CLIs.

Verification

The documented schema, approval kinds, and per-kind fields were checked against the product source. Examples are valid JSON and consistent with the schema table. Locally ran npm ci and the docs content linter (lint-content) on the changed files; the repo's pre-commit content lint also passed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-06-25T22:43:59Z

How to review these changes 👓

Thank you for your contribution. To review these changes, choose one of the following options:

A Hubber will need to deploy your changes internally to review.

Table of review links

Note: Please update the URL for your staging server or codespace.

The table shows the files in the content directory that were changed in this pull request. This helps you review your changes on a staging server. Changes to the data directory are not included in this table.

Source	Review	Production	What Changed
`copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md`	fpt ghec	fpt ghec
`copilot/reference/copilot-cli-reference/cli-config-dir-reference.md`	fpt ghec	fpt ghec

Key: fpt: Free, Pro, Team; ghec: GitHub Enterprise Cloud; ghes: GitHub Enterprise Server

🤖 This comment is automatically generated.

Copilot

Pull request overview

Expands the GitHub Copilot CLI documentation for permissions-config.json, covering where it’s stored, how location scoping works, and the approval schema so users can reliably migrate or author persisted tool/path approvals.

Changes:

Added detailed reference documentation for permissions-config.json (resolution order, location keying, schema, approval kinds, and examples).
Documented command identifier and directory matching behavior used by persisted approvals.
Added a “persisted permissions” explanation and cross-links from the tool-permissions how-to.

Show a summary per file

File	Description
content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md	Adds full reference coverage for `permissions-config.json` location resolution, schema, approval kinds, and examples.
content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md	Explains persisted approvals and links to the detailed reference section.

Copilot's findings

Files reviewed: 2/2 changed files
Comments generated: 1

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

chaiphet6669-afk · 2026-06-26T02:44:04Z

https://tree-sitter.github.io/tree-sitter/#third-party

I see you've shared the README.md file from your fork of the swift-tree-sitter repository. This is a Swift API wrapper for the tree-sitter incremental parsing system.

Key points about this project:

Two main components:
- SwiftTreeSitter - A low-level wrapper closely matching the C runtime API
- SwiftTreeSitterLayer - A higher-level abstraction supporting nested languages and async operations
Core features:
- Close coverage of the C API with Swift/Foundation types
- Standard query result mapping for syntax highlighting and injections
- Query predicate/directive support
- Nested language support
- Swift concurrency support
Integration: It's available as an SPM package with examples for integrating both components
Language support: The README includes an extensive table of 50+ tree-sitter language parsers with SPM support

Is there something specific you'd like to do with this repository? I can help you with:

Creating issues or pull requests
Understanding the code structure
Making modifications to files
Setting up workflows or configurations
Or anything else related to your fork

What would you like to work on?

chaiphet6669-afk

``content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md

content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md
> ```````
26f0db85d799f5477fbe902bc8c1f2e706e314dehttps://tree-sitter.github.io/tree-sitter/#third-party

hubwriter

@danmoseley - This looks good. The docs file content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md is auto-updated by AI based on the docs in the dev repo so the lack of detail suggests this was missing from the internal docs. Thanks for adding.

I've made one correction, changing:

Saved URL rules are stored in config.json, not in permissions-config.json.

to:

Saved URL rules are stored in settings.json, not in permissions-config.json.

github-actions · 2026-06-26T11:04:55Z

Thanks very much for contributing! Your pull request has been merged 🎉 You should see your changes appear on the site in approximately 24 hours. If you're looking for your next contribution, check out our help wanted issues ⚡

danmoseley and others added 2 commits June 25, 2026 16:43

Improve Copilot CLI permissions config docs

aec5663

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Clarify persisted Copilot CLI approvals

128719b

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 25, 2026 22:43

github-actions Bot added the triage Do not begin working on this issue until triaged by the team label Jun 25, 2026

Copilot started reviewing on behalf of danmoseley June 25, 2026 22:43 View session

Copilot AI reviewed Jun 25, 2026

View reviewed changes

Comment thread content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md Outdated

danmoseley and others added 2 commits June 25, 2026 16:46

Potential fix for pull request finding

00d0dd2

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Note automatic removal of orphaned location entries

c05b0e9

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

chaiphet6669-afk reviewed Jun 26, 2026

View reviewed changes

hubwriter reviewed Jun 26, 2026

View reviewed changes

Comment thread content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md Outdated

Apply suggestion from @hubwriter

005129a

hubwriter approved these changes Jun 26, 2026

View reviewed changes

Merge branch 'main' into copilot-cli-permissions-config-docs

a56679a

hubwriter enabled auto-merge June 26, 2026 10:58

hubwriter added this pull request to the merge queue Jun 26, 2026

Merged via the queue into github:main with commit 65ff838 Jun 26, 2026
40 checks passed

danmoseley deleted the copilot-cli-permissions-config-docs branch June 26, 2026 15:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Document Copilot CLI permissions-config.json schema and persisted approvals#44916

Document Copilot CLI permissions-config.json schema and persisted approvals#44916
hubwriter merged 6 commits into
github:mainfrom
danmoseley:copilot-cli-permissions-config-docs

danmoseley commented Jun 25, 2026

Uh oh!

github-actions Bot commented Jun 25, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

chaiphet6669-afk commented Jun 26, 2026

Uh oh!

chaiphet6669-afk left a comment •

edited

Loading

Uh oh!

Uh oh!

hubwriter left a comment •

edited

Loading

Uh oh!

Uh oh!

github-actions Bot commented Jun 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

danmoseley commented Jun 25, 2026

What this changes

Why

Verification

Uh oh!

github-actions Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to review these changes 👓

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

chaiphet6669-afk commented Jun 26, 2026

Uh oh!

chaiphet6669-afk left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hubwriter left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions Bot commented Jun 25, 2026 •

edited

Loading

chaiphet6669-afk left a comment •

edited

Loading

hubwriter left a comment •

edited

Loading